Alchemy Help:
The view from 30,000 feet

Overview

Let's start this discussion by saying that millions of C, C++, BASIC, Pascal and (insert your favorite programming language here) programmers have walked this path before you, and have made the transition from command-line tools and single-source editors to an integrated environment. You will find that working this way is a much more natural approach to developing your web site, and it will also save you an incredible amount of time. The Alchemy environment is very flexible in that you are not required to use the built-in tools and editors. We have designed it in such a way that it integrates seamlessly with most third-party applications, so you can use whatever external tools you are comfortable with. For example, if you want to use an HTML editor such as HotDog® or HoTMetaL® instead of the internal Web Editor, just plug it in by telling Alchemy where to find the application. The same is true for image editors, web browsers and just about any other application you can think of.

Unlike HTML editors, which focus on creating individual HTML files, Alchemy is based on the concept of a project. All of the elements of your web site go into a project file which is managed by Alchemy. You access your project via the Project Window, which is the main Alchemy application window. The Project Window keeps track of the contents of your HTML files and displays them graphically, and you can edit or view any of the project elements (graphics files, HTML source, CGI-BIN scripts, audio clips, Java applets, etc.) by clicking them with the mouse. In addition, you can easily upload your project to your web server at any time by clicking the Upload button. Since Alchemy allows you to surf your web site on your PC, you do not need to connect to a server until you are ready to upload your project.

The downside of using an IDE's project-oriented approach is that you will probably need to work a bit differently than you have in the past. The basic premise of the Alchemy IDE is that you will create a directory on your PC, and you will upload your project to a matching directory on the server. In essence, the PC directory is an exact duplicate of the server directory. This will allow you to surf your web site on the PC with a web browser exactly as you would if you were connected to the server, but you do not need to be online while developing the web site. Here are the rules you need to follow in order to make this work:

1. All files go into the same directory
All of the files which make up your project (HTML documents, graphics files, Perl scripts, etc.) go into a single directory, which is known as the project directory. You will have a project directory on your local PC, and there will be a matching project directory on the server. While most developers create multiple subdirectories in order to make their files easier to manage (one for graphics files, one for HTML files, etc.) you cannot do this with Alchemy, and you don't need to since Alchemy manages the files for you. This makes no difference to Unix, the HTTP server or your users, but you will need to get over the mental hurdle of having a messy directory.

2. All files have DOS-style 8.3 file names
Since you will probably be crossing an operating system barrier (DOS to Unix/Mac/Windows NT/Who-knows-what), all of your files must have an 8.3 file name since it's the lowest common denominator. For example, don't name your home page "MySite.MyFirstHomePage.html", name it "homepage.htm". Note: Your server probably has strict naming requirements for the home page ("index.html", for example, which is not an 8.3 name) and Java applets (which must end with ".class"), among other things. You can configure Alchemy to automatically rename files while uploading them to the server; more on this later.

3. All files references are non-pathed
All references to files that are part of your web site (with the exception of CGI-BIN files, we'll discuss this in a minute) are non-pathed local file references. That's a mouthful, so here's what it means. Let's say that:

• Your web site's URL is "http://www.mysite.com".
• Your web site is in the "/websites/mysite" directory on your server.
• Your home page is the file "/websites/mysite/homepage.htm".
• You have the graphic file "/websites/mysite/welcome.gif" which is referenced by your home page.

• Not "IMG SRC="/websites/mysite/welcome.gif""
  
• Not "IMG SRC="file://www.mysite.com/welcome.gif""
  
• Not "IMG SRC="http://www.mysite.com/welcome.gif""
  

Likewise, if you have a link to your home page from another HTML file in your site, the Begin-anchor tag would appear as "A HREF="homepage.htm"", just the file name all by itself.

Note that this only applies to files that are part of your web site, i.e., files that you are creating on your PC and will be uploading to the server. You can still refer to files in other directories on the server or on other machines on the web, but Alchemy will ignore them as it will not consider them to be part of your project.

NOTE: Alchemy requires items 1 & 3 above due to a web browser limitation. Until very recently, browsers were not able to follow links into subdirectories when accessing local files. It appears that the major browser manufacturers are now addressing this limitation; the latest version of Netscape allows access to subdirectories while browsing locally. So, we will be removing requirements 1 & 3 shortly, and you will be able to have subdirectories in your project.

By following the above rules, what you are essentially doing is creating a web site on your PC which can be mirrored on your server. Not only can the contents of the project directory can be uploaded to the server without making any changes to the sources, but the web site will act just the same on your PC as it will on the server (with the constant exception of CGI-BIN, we'll get to that). This means that you can build and test your whole site off-line and then upload it to the server when you're ready. Of course, if you have references to other resources on the network (like "A HREF="http://www.cool-links.com") you'll still need to be on-line to test them from your PC.

There will be times when you have a file which is part of your project but Alchemy will not know where to upload it because it is not referred to using a non-pathed local reference. For example, let's say that you have a ZIP'ed file that you are allowing users to download from your FTP site. The reference on your HTML page would look something like "A HREF="ftp://www.mysite.com/myfile.zip"", but the actual file on the server would be something like "/pub/mysite/ftp/myfile.zip" and would not appear as such anywhere in the project. When reading the HTML source, Alchemy can figure out that it's supposed to upload the file "myfile.zip", but it has no way of knowing where to put it since the HREF does not contain the server directory name.

To deal with this situation, just add a new folder to your project in the Project window, indicate the server directory to associate with the folder and add the file to the folder. In the above example, you could create a folder named "FTP", associate it with the server directory "/pub/mysite/ftp", and add the file "myfile.zip" to the folder.

To get around this problem, Alchemy allows you to specify both local and server versions of the home page file name. In the above example, when you create or modify your project in the Project dialog you would set the server file name to "index.html" and the local file name to "index.htm". "index.htm" is the file you create on your PC. When you upload your project to the server, the file "index.htm" is sent to the server, and is then copied to the file "index.html". Note that we said copied, not renamed. This is because all of your HTML documents that have links to the home page are going to be looking for "index.htm", not "index.html". If you specify "index.html" in the links, Alchemy will not be able to find the file and you will not be able to surf your web site on the PC. Got it?

This may bother you at first, but it has a very interesting and beneficial side effect: you never access the actual home page "index.html" from within your web site. This means that the only time the actual home page is "touched" is when someone connects to your web site and the HTTP server delivers it to their web browser. After that, whenever they access a link within your site that takes them "back to the home page", they get "index.htm", not "index.html". Which means... that when you get your next activity report for your web site, the number of home page "hits" is going to be the actual number of people who visited your web site, and your counter that says "you are the ###th person to visit this site" will actually be true for a change!

Of course, your visitor's web browser probably caches the home page anyway, in which case you can ignore that last paragraph.

The good new is, we have come up with a solution to this problem. The bad news is, it's not in the current release of Alchemy. In the next release, we intend to provide support for off-line testing of Perl scripts, along with any other scripting languages (Tcl, Unix shell, etc.) for which DOS interpreters exist. If you are using a Windows 3.x/95 server, you'll also be able to test CGI executables (i.e., .EXE's) but if your web site will end up on a Unix/Mac/etc. host then you're stuck with scripts.

In the meantime, we will provide as much CGI support as we can. The current version of Alchemy recognizes files with the following file name extensions as CGI files:

• .PL - Perl scripts
• .TCL - Tcl scripts
• .SH - Shell scripts
• .C - C source
• .CPP - C++ source

FORM METHOD="POST" ACTION="/cgi-bin/mysite/signup.pl"

Alchemy will assume that the file "signup.pl" is a Perl script which can be found in your project directory. When you upload your project to the server, Alchemy will copy the file to the CGI directory that you have defined for your project, "/pub/cgi-bin/mysite. Note that Alchemy will not attempt to copy the file to the directory "/cgi-bin/mysite" that is specified in the FORM tag, since it is most likely an aliased path and thus the transfer would fail.

In addition to automatically uploading CGI files that it understands, Alchemy creates a folder in the Project window called CGI-BIN which is associated with the CGI directory on the server. Anything you put in this folder will be copied to the CGI directory on the server when you upload your project, even if Alchemy doesn't recognize the file extension.

Okay, we said up front that we wouldn't explain anything about how to write CGI code, but here are some hints we've found useful in making your CGI development cycle a little bit shorter and a little less painful. These apply to DOS/Windows in general as well as to Alchemy:

• Use Perl - There's a lot of really good source code out there, and if you understand CGI in the first place then you can certainly get your brain wrapped around Perl.

• Test it off-line first - Let's say that you have a Perl script called "mailform.pl" that takes the contents of a form, writes them to a mailing list file and generates an HTML page that thanks the user for their input.

  • Edit your script, then run it through the DOS-based Perl interpreter before uploading it to the server to check for syntax errors, as in "perl mailform.pl". Continue this edit/interpret cycle until there are no more syntax errors.
  • Temporarily assign values to the form variables from within the script. For example, if there's a 'name' field on the form, assign it the value 'J. Jones'. Now your script will have something to chew on when you run it through the interpreter so that you can see some valid output.
  • If you have pathed references in your script (i.e., "/cgi-bin/mycompany/maillist.txt"), temporarily change them to non-pathed local references (i.e., "maillist.txt"). Now you can do file I/O to the mailing list file on your PC.
  • Since the HTML page that is produced by a form script comes from stdout (i.e., it's printed to the screen) you can redirect it to a file, as in "perl mailform.pl > thankyou.htm". Now you can view the output page in your web browser and change the script code until you like the results.

• Let Alchemy upload it - Once you're at the point where your script is basically working and you need to test it on the server, you will get into the inevitable edit it/upload it/surf it cycle. Let Alchemy take care of the "upload it" part since it will copy your files to the host and change the access permissions in one shot. Put away those FTP and Telnet apps and save yourself some time!